How Pelican: Part 1

I've posted on why I picked Pelican as a static blog generator but now I'm going to get into the nuts and bolts of how to use it. It does require you not be afraid to edit configuration files, and a little knowledge of Python and markup languages will go a long way. You will also need a webserver, but if you just want to get your feet wet, there are plenty of free hosting providers you can try out before you fork out for hosting. However if you want to use Pelican hopefully this will be a good introduction.

The first thing you'll need to make sure you have the Python interpreter installed on your operating system. If you use Linux or Mac OSX you probably don't need to worry but if your using Windows you can find various options here.

Once you've made sure that Python is installed you need to download the Pelican source code which can be found here. If you are familiar with Git then you probably don't need any help and can just skip to my config files to have nose about how I've set things up (it's nothing fancy). If not then this is an excellent guide, or alternatively you can just download this zip file.

If you're still using windows then from here on in I have no experience as I'm using the Linux Distro Linux Mint. However It should be possible to use a combination of pip and fabric to get yourself up and running. You'll also have to use the Windows PowerShell which will be fun...

Once you've either cloned the git repository or unzipped the file you need to install Pelican, the Pelican website has an excellent guide on how to do so. And then run the: 'pelican-quickstart' command.

This will run a programme the will ask you the questions below:

Welcome to pelican-quickstart v3.3.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? MyTitle
> Who will be the author of this web site? Me
> What will be the default language of this web site? [en] 
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10] 10
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) y
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost] 
>  What is the port of your SSH server? [22] 
> What is your username on that server? [root] 
> Where do you want to put your web site on that server? [/var/www] 
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n

Done. Your new project is available at /home/bloglocation

These are sample answers and you'll have to respond with settings relevant to how you want to manage your new blog. I'm using SSH to push files directly to my web server because it's cool. FTP is fine. I haven't tried using Dropbox and other fancy things but I imagine if using multiple workstations it could be awesome.

Now you need to edit your config files. This is where a working knowledge of Python will be necessary. If you need to learn then Learn Python The Hard Way is what I used. Open your pelicanconf.py and publishconf.py files in the text editor of your choice and change the variables so that you get the site of you're design. My files looks like this (I've removed server locations and the like):

pelicanconf.py

#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals

AUTHOR = u'Joe Poser'
SITENAME = u'JPoser/Blog'
SITEURL = ''

# Sets the theme

THEME = "/home/joe/JPoser/pelican-themes/pelican-bootstrap3"
# Activates plugins
PLUGIN_PATH = "/home/joe/JPoser/plugins"
PLUGINS = ['sitemap']

TIMEZONE = 'Europe/Paris'

DEFAULT_LANG = u'en'

# Feed generation is usually not desired when developing
FEED_DOMAIN = 'www.jposer.net'
FEED_ATOM = None
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
FEED_RSS = 'feeds/rss.xml'
CATEGORY_FEED_RSS = 'feeds/category/%s.rss.xml'
FEED_ALL_RSS = 'feeds/all.rss.xml'
TRANSLATION_FEED_ATOM = None

# Feeds
FEEDS = (('All posts', 'feeds/all.rss.xml'),
         ('Category', 'feeds/category'),)

# Formatting for dates

DEFAULT_DATE_FORMAT = ('%a %d %B %Y')

# Formatting for urls

ARTICLE_URL = "posts/{date:%Y}/{date:%m}/{slug}/"
ARTICLE_SAVE_AS = "posts/{date:%Y}/{date:%m}/{slug}/index.html"

CATEGORY_URL = "category/{slug}"
CATEGORY_SAVE_AS = "category/{slug}/index.html"

TAG_URL = "tag/{slug}/"
TAG_SAVE_AS = "tag/{slug}/index.html"

# Generate yearly archive

YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'

# Blogroll
LINKS =  (('Pelican', 'http://getpelican.com/'),
          ('Python.org', 'http://python.org/'),
          ('Jinja2', 'http://jinja.pocoo.org/'),
          ('London Hackspace', 'https://london.hackspace.org.uk/'),)

# Social widget
SOCIAL = (('Twitter', 'https://twitter.com/j_poser'),
          ('Github', 'https://Github.com/JPoser'),
          ('Google+', 'https://plus.google.com/106215649768396140352'),
          ('LinkedIn', 'http://uk.linkedin.com/pub/joseph-poser/32/502/703'),
          ('RSS', 'http://jposer.net/feeds/all.rss.xml'),)

DEFAULT_PAGINATION = 8

# Uncomment following line if you want document-relative URLs when developing
#RELATIVE_URLS = True

# Site Map Settings
SITEMAP = {
    'format': 'xml',
    'priorities': {
    'articles': 0.5,
    'indexes': 0.5,
    'pages': 0.5
   },
   'changefreqs': {
       'articles': 'monthly',
       'indexes': 'daily',
       'pages': 'monthly'
   }
}

In reference to this config, some of the variables are related to plugins and themes I'm runnning in Pelican. I'll be expanding on the use of these in future posts.

publishconf.py

'#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals

# This file is only used if you use `make publish` or
# explicitly specify it as your config file.

import os
import sys
sys.path.append(os.curdir)
from pelicanconf import *

SITEURL = 'http://jposer.net'
RELATIVE_URLS = False

FEED_ALL_ATOM = 'feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'
TAG_FEED_ATOM = 'feeds/tag/%s.atom.xml'

DELETE_OUTPUT_DIRECTORY = True

# Following items are often useful when publishing

DISQUS_SITENAME = ""
GOOGLE_ANALYTICS = ""

Once you've done all this work you're almost ready to start posting. In the next post I'll run through theming, using Markdown to write content and pushing that content to the internet tubes!

Comments

comments powered by Disqus